This pr defers all Python classes & interfaces into factory functions and replaces cross-module imports with lazy proxy objects. This enables us to actually make submodule contents lazy and reduces the time taken to import python submodules by ~55%

The problem can be defined as follows - Before, if a user wrote import aws_cdk.aws_s3, Python had to

• Execute its cross-module imports at the top of the init file (for example, aws_iam)
• Build its classes, interfaces, and objects
• Register all types with the jsii runtime

This lead to a cascading init which would scale as the size of the library grows. To solve this, we introduce lazy factories.

Part 1 - making base classes lazy

All classses, interfaces, and structs are wrapped in @_memoized factory functions, for example:

# Before (eager)
class Bucket(metaclass=jsii.JSIIMeta, jsii_type="aws-cdk-lib.aws_s3.Bucket"):
    ...

# After (lazy)
@_memoized
def _lazy_build_Bucket() -> type:
    class Bucket(metaclass=jsii.JSIIMeta, jsii_type="aws-cdk-lib.aws_s3.Bucket"):
        ...
    return Bucket

getattr on the module triggers the factory on first access, which then subsequently caches the module.

Furthermore, typecheckers like mypy and pyright see the full class shapes via stubs in an if typing.TYPE_CHECKING: block. These stubs have empty bodies and are never executed at runtime. The reason for this is that type checkers evaluate code statically and need to see class definitions with their full signatures. Since the factory functions hide the class inside a closure, type checkers don't like this and therefore we need stubs.

Part 2 - making annotation-only imports lazy

Cross-module imports exist mainly to support type annotations. Since all type annotations are rendered as string literals, they never actually trigger module loading at definition. Therefore, these imports are annotation-only and are only needed at runtime when code actively uses the imported type

We exploit this by placing the real import under if typing.TYPE_CHECKING: (for static analysis) and using a _LazyImport proxy in the else branch that defers importlib.import_module() until first attribute access:

# Before (eager — triggers cascading module loads at import time)
import scope.jsii_calc_base_of_base as _mod

# After (lazy — module only loads when _mod.SomeType is actually accessed)
if typing.TYPE_CHECKING:
    import scope.jsii_calc_base_of_base as _mod
else:
    _mod = _LazyImport("scope.jsii_calc_base_of_base")

Note

With lazy class factories, classes don't register themselves with the jsii runtime until their factory runs. This is a problem when the kernel returns object references with type FQNs which aren't registered. As an example, if the user never directly accessed aws_cdk.aws_s3.Bucket in their Python code (so the factory never ran), the runtime does not know which class to deserialize that reference into.

The _reference_map.py in the Python runtime now handles lazy types. For instance, when the kernel returns a type reference that isn't yet registered, it triggers getattr on the appropriate module to materialize the factory, which registers the type as a side effect of class construction via JSIIMeta.

EDGE CASES

This section is basically weird things I encountered which my solution also accounts for in the code.

Same-module base class references

When class B(A) and A are both in the same module, A doesn't exist yet when B's factory runs (both are deferred). The generated code replaces bare base class names with factory calls:

class B(_lazy_build_A(), metaclass=jsii.JSIIMeta, ...):
    ...

typing.get_type_hints() needs all deferred classes resolved

jsii-pacmak generates runtime type-checking code that validates method arguments at call time. This includes the typechecking call and the typechecking stub which you can see at the end of a module. typing.get_type_hints() looks at the stubs annotations dict and resolves each string in a namespace. Previously, stubs had unquoted annotations, and typing.get_type_hints() was called with no explicit namespace (which I think it defaulted to the stub's globals). This was fine becuse all classes existed in globals() at module scope. Now classes are deferred. They don't exist in globals() until their factory runs.

To solve this, we introduce _get_typechecking_ns(), which builds a dict that's a copy of globals() plus every deferred class (by calling all factories). We pass this dict as globalns so get_type_hints() can find any name.

Before

if __debug__:
    type_hints = typing.get_type_hints(_typecheckingstub__abc123)
    check_type(...)

After

if __debug__:
    type_hints = typing.get_type_hints(_typecheckingstub__abc123, globalns=_get_typechecking_ns(), localns=_get_typechecking_localns())
    check_type(...)

qualname issues

Python automatically sets qualname based on where a class is defined lexically. A class inside a function gets function_name..ClassName. Since we define classes inside lazy_build* functions, they'd show up as _lazy_build_Bucket..Bucket in error messages (an example), tracebacks, and repr() instead of just Bucket.

The fix is a single line after the class is created inside the factory:
Bucket.__qualname__ = "Bucket"

Intersection type helper classes

When a parameter is typed as A & B in TypeScript, pacmak generates a synthetic Protocol class that extends both interfaces (for instance, think class _ISomething_IFriendly(ISomething, IFriendly, Protocol). These helper classes were previously emitted at module scope where their base classes already existed in globals(). With lazy factories, the base classes are now factories, which causes a NameError.

The fix basically moves the helper classes into the else block of if typing.TYPE_CHECKING and replaces same-module base class names with their factory call.

# Before (broken — ISomething not in globals at import time)
class _ISomething_IFriendly(ISomething, _other_pkg.IFriendly, typing_extensions.Protocol):
    pass

# After (works — factory call materializes ISomething)
class _ISomething_IFriendly(_lazy_build_ISomething(), _other_pkg.IFriendly, typing_extensions.Protocol):
    pass

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.